/** 
 * Copyright (C) 2012 Foxit Corporation. 
 * All Rights Reserved.
 *
 * The following code is copyrighted and contains proprietary information and trade secrets of Foxit Corporation. 
 * You can only redistribute files listed below to customers of your application, under a written SDK license agreement with Foxit. 
 * You cannot distribute any part of the SDK to general public, even with a SDK license agreement. 
 * Without SDK license agreement, you cannot redistribute anything.
 *
 * @file	fpdfobject.h
 * @brief	Header file for the PDF object module.
 * @details	The PDF object module offers:
 *			1. Methods for getting document catalog, info object.<br>
 *			2. Methods for operating PDF basic types of objects:<br>
 *				<b>Boolean values</b>
 *				<b>Integer and real numbers</b>
 *				<b>Strings</b>
 *				<b>Names</b>
 *				<b>Arrays</b>
 *				<b>Dictionaries</b>
 *				<b>Streams</b>
 *				<b>null object</b>
 *				<b>indirect object</b>
 * @note	If you want to purchase Foxit PDF SDK license and use ANY of the following functions, please
 *			request for enabling PDF object module explicitly. 
 */

/** 
 * @addtogroup FGSPDFOBJECT PDF Object 
 * @brief Methods in this module are included in fpdfobject.h.
 */
 
 /** @{ */

#ifndef __FGSPDFOBJECT__
#define __FGSPDFOBJECT__

#include "fpdfbase.h"

#ifdef __cplusplus
extern "C" {
#endif

/** 
 * @brief Get document catalog object.
 *
 * @param[in]	  document		Reference to a PDF document.
 *
 * @return	A FGSPDFObjectRef reference that receives the catalog object. 
 *			It should be a dictionary.  NULL for failure.
 */
FGSPDFObjectRef FGSPDFDocGetCatalog(FGSPDFDocumentRef document);

    
/** 
 * @brief Get document info object. (PDF Reference, Section 10.2.1)
 *
 * @param[in] document		Reference to a PDF document.
 *
 * @return	A FGSPDFObjectRef reference that receives the info object. 
 *			It should be a dictionary. NULL for failure.
 */
FGSPDFObjectRef FGSPDFDocGetInfo(FGSPDFDocumentRef document);

    
/** 
 * @brief Get type of an object.
 *
 * @param[in] obj		Reference to the object.
 *
 * @return	An integer that identifies the object type. See the enum definitions <b>FGSPDFObjectType</b>.
 */
FGSPDFObjectType FGSPDFObjectGetType(FGSPDFObjectRef obj);

/** 
 * @brief Get integer value from an object.
 *
 * @param[in] obj		Reference to the object.
 *
 * @return	An integer.     If the parameter  is a boolean object, return 0 for false and 1 for true;<br>
 *							if the parameter  is a number object, return the integer part of the number;<br>
 *							for all other object types or invalid object, return 0.
 */
SInt32 FGSPDFObjectGetInteger(FGSPDFObjectRef obj);

/** 
 * @brief Get floating number value from an object.
 *
 * @param[in]	  Reference to the object.
 *
 * @return	An Float32 value.	If the parameter  is a number object, return value of the number;<br>
 *								for all other object types or invalid object, return 0.
 */
Float32 FGSPDFObjectGetFloat(FGSPDFObjectRef obj);


/** 
 * @brief Get floating number value from an object.
 *
 * @param[in]		  Reference to the object.
 *
 * @return	A CFStringRef value. If the parameter  is a string object, return value of the string.
 */
CFStringRef FGSPDFObjectCopyString(FGSPDFObjectRef obj, Boolean bUnicode);
    
/** 
 * @brief Get boolean value of the object. Applicable to boolean object.
 *
 * @param[in] obj			Reference to the object.	
 *
 * @return A boolean value. If not success, this will be set to <b>FALSE</b>.
 */
Boolean FGSPDFObjectGetBoolean(FGSPDFObjectRef obj); 

/** 
 * @brief Create a boolean object from a single boolean value.
 *
 * @param[in] boolean		A boolean value.		 
 *
 * @return A FGSPDFObjectRef reference that receives the boolean object.
 */
FGSPDFObjectRef FGSPDFObjectCreateBoolean(Boolean boolean);

/** 
 * @brief Create a number object from an integer.
 *
 * @param[in] number		The input integer.		
 *
 * @return A FGSPDFObjectRef reference that receives the number object. 
 */
FGSPDFObjectRef FGSPDFObjectCreateInteger(SInt32 number); 

/** 
 * @brief Create a number object from a floating-point value.
 *
 * @param[in] number		The input floating-point.		 
 *
 * @return A FGSPDFObjectRef reference that receives the number object.
 */
FGSPDFObjectRef FGSPDFObjectCreateFloat(Float32 number); 
   
/** 
 * @brief Create a string object from a byte string or a unicode string. Optionally hex flag can be set.
 *
 * @param[in] string		The input CFString reference.
 * @param[in] bHex			The input hex flag.
 * @param[in] bUnicode		The input unicode flag.
 *
 * @return A FGSPDFObjectRef reference that receives the string object. 
 */
FGSPDFObjectRef FGSPDFObjectCreateString(CFStringRef string, Boolean bHex, Boolean bUnicode);

/** 
 * @brief Create a name object from a byte string.
 *
 * @param[in] string		The input CFString reference.
 *
 * @return A FGSPDFObjectRef reference that receives the string object. 
 */
FGSPDFObjectRef FGSPDFObjectCreateName(CFStringRef string, Boolean bUnicode);

/** 
 * @brief Create an empty array object.
 *
 * @return A FGSPDFObjectRef reference that receives the array object. 
 */ 
FGSPDFObjectRef FGSPDFObjectCreateArray();
    
/** 
 * @brief Create an empty dictionary object.	
 *
 * @return A FGSPDFObjectRef reference that receives the dictionary object. 
 */ 
FGSPDFObjectRef FGSPDFObjectCreateDict();
    
/** 
 * @brief Create an empty stream object.
 *
 * @param[in] dict			Pointer to a dictionary for the stream object.
 *
 * @return A FGSPDFObjectRef reference that receives the stream object. 
 *
 * @note The newly created stream object has no data, so ::FGSPDFStreamSetData should be called next to set data to the stream object.
 */
FGSPDFObjectRef FGSPDFObjectCreateStream(FGSPDFObjectRef dict); 
    
/** 
 * @brief Get the object number.
 *
 * @param[in] obj			Reference to the object.	
 *
 * @return A UInt32 that receives the object number.
 *
 * @note The object number is always above 0.
 */
UInt32 FGSPDFObjectGetObjNumber(FGSPDFObjectRef obj);
    
/** 
 * @brief Create a reference object with the indirect object collection and referred object.
 *
 * @param[in] doc			Reference to a PDF document.
 * @param[in] refObj		Reference to the referred object.	
 *
 * @return A FGSPDFObjectRef reference that receives the reference object. 
 */
FGSPDFObjectRef FGSPDFObjectCreateReference(FGSPDFDocumentRef doc, FGSPDFObjectRef refObj);
    
/** 
 * @brief Create a reference object with the indirect object collection and referred object number.
 *
 * @param[in] doc			Reference to a PDF document.
 * @param[in] objNum		The referred object number.		
 *
 * @return A FGSPDFObjectRef reference that receives the reference object. 
 */ 
FGSPDFObjectRef FGSPDFObjectCreateReference2(FGSPDFDocumentRef doc, UInt32 objNum);
    
/** 
 * @brief Count elements in the array.
 *
 * @param[in] array			Reference to an array object.	
 *
 * @return An integer that receives the count of elements.  -1 means error.
 */ 
SInt32 FGSPDFArrayCountElements(FGSPDFObjectRef array); 
    
/** 
 * @brief Get the specified element in the array.
 *
 * @param[in] array			Reference to an array object.
 * @param[in] index			Specify the zero-based index in the array. 		
 *
 * @return A FGSPDFObjectRef reference that receives the specified element. 
 */ 
FGSPDFObjectRef FGSPDFArrayGetElement(FGSPDFObjectRef array, SInt32 index);

/** 
 * @brief Get a byte string with specified position in the array.
 *
 * @param[in] array			Reference to an array object.
 * @param[in] index			Specify the zero-based index in the array. 	 
 *
 * @return An CFString Reference used to receive the byte string and its length.
 */
CFStringRef FGSPDFArrayCopyString(FGSPDFObjectRef array, SInt32 index, Boolean bUnicode); 

/** 
 * @brief Get an integer with specified position in the array.
 *
 * @param[in] array			Reference to an array object.
 * @param[in] index			Specify the zero-based index in the array. 
 *
 * @return An integer that receives the specified integer.
 */
SInt32 FGSPDFArrayGetInteger(FGSPDFObjectRef array, SInt32 index); 
    
/** 
 * @brief Get a floating-point with specified position in the array.
 *
 * @param[in] array			Reference to an array object.
 * @param[in] index			Specify the zero-based index in the array.  
 *
 * @return A floating-point that receives the specified floating-point value.
 */
Float32 FGSPDFArrayGetFloat(FGSPDFObjectRef array, SInt32 index); 
    
/** 
 * @brief Get a dictionary object with specified position in the array.
 *
 * @param[in] array			Reference to an array object.
 * @param[in] index			Specify the zero-based index in the array. 		
 *
 * @return A FGSPDFObjectRef reference that receives the specified dictionary object.
 */
FGSPDFObjectRef FGSPDFArrayGetDict(FGSPDFObjectRef array, SInt32 index);

/** 
 * @brief Get array value of the specified element in the array.
 *
 * @param[in] array			Reference to an array object.
 * @param[in] index			Specify the zero-based index in the array. 
 *
 * @return A FGSPDFObjectRef reference that receives the specified array object. <b>NULL</b> for non-array objects.
 */
FGSPDFObjectRef FGSPDFArrayGetArray(FGSPDFObjectRef array, SInt32 index);
    
/** 
 * @brief Get a stream object with specified position in the array.
 *
 * @param[in] array			Reference to an array object.
 * @param[in] index			Specify the zero-based index in the array. 		
 *
 * @return	A FGSPDFObjectRef reference that receives the specified steram object.
 */
FGSPDFObjectRef FGSPDFArrayGetStream(FGSPDFObjectRef array, SInt32 index);

/** 
 * @brief Insert an element at specified position in the array.
 *
 * @param[in] array			Reference to an array object.
 * @param[in] index			Specify the zero-based index in the array. 
 * @param[in] element		Reference to the input object.
 *
 * @return ::kFGSErrorSuccess means success.<br>
 *		   For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFArrayInsertAt(FGSPDFObjectRef array, SInt32 index, FGSPDFObjectRef element);
    
/** 
 * @brief Change the element at specified position in the array.
 *
 * @param[in] array			Reference to an array object.
 * @param[in] index			Specify the zero-based index in the array. 
 * @param[in] element		Reference to the input object.
 *
 * @return ::kFGSErrorSuccess means success.<br>
 *		   For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFArraySetAt(FGSPDFObjectRef array, SInt32 index, FGSPDFObjectRef element); 
    
/** 
 * @brief Remove the element at specified position in the array.
 *
 * @param[in] array			Reference to an array object.
 * @param[in] index			Specify the zero-based index in the array. 
 *
 * @return ::kFGSErrorSuccess means success.<br>
 *		   For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFArrayRemoveAt(FGSPDFObjectRef array, SInt32 index); 
    
/** 
 * @brief Add an element to the array.
 *
 * @param[in] array			Reference to an array object.
 * @param[in] element		Reference to the input object.
 *
 * @return ::kFGSErrorSuccess means success.<br>
 *		   For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFArrayAdd(FGSPDFObjectRef array, FGSPDFObjectRef element); 

/** 
 * @brief Add a byte string or a unicode string to the array. Optionally hex flag can be set.
 *
 * @param[in] array			Reference to an array object.
 * @param[in] string		The input CFString reference.
 * @param[in] bHex			The input hex flag.
 * @param[in] bUnicode		The input unicode flag.
 *
 * @return ::kFGSErrorSuccess means success.<br>
 *		   For more definitions please see enum definitions <b>FGSErrorRet</b>. 
 */
FGSErrorRet FGSPDFArrayAddString(FGSPDFObjectRef array, Boolean hex, CFStringRef string, Boolean bUnicode); 
    
/** 
 * @brief Add a Integer element to the array.
 *
 * @param[in] array			Reference to an array object.
 * @param[in] number		The input Integer.
 *
 * @return ::kFGSErrorSuccess means success.<br>
 *		   For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFArrayAddInteger(FGSPDFObjectRef array, SInt32 number); 

/** 
 * @brief Add a floating-point element to the array.
 *
 * @param[in] array			Reference to an array object.
 * @param[in] number		The input floating-point.
 *
 * @return ::kFGSErrorSuccess means success.<br>
 *		   For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFArrayAddFloat(FGSPDFObjectRef array, Float32 number); 

/** 
 * @brief Add a string element to the array.
 *
 * @param[in] array			Reference to an array object.
 * @param[in] string		The byte string or unicode string.
 * @param[in] bUnicode		The input unicode flag.
 *
 * @return ::kFGSErrorSuccess means success.<br>
 *		   For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFArrayAddName(FGSPDFObjectRef array, CFStringRef string, Boolean bUnicode); 

/** 
 * @brief Get a matrix element from the array.
 *
 * @param[in] array			Reference to an array object.
 *
 * @return	A CGAffineTransform object. Only available when array is composed by six floating-point.
 */
CGAffineTransform FGSPDFArrayGetMatrix(FGSPDFObjectRef array); 

/** 
 * @brief Get a rect element from the array.
 *
 * @param[in] array			Reference to an array object.
 *
 * @return	A CGRect object. Only available when array is composed by four floating-point.
 */
CGRect FGSPDFArrayGetRect(FGSPDFObjectRef array);

/** 
 * @brief	Check if the dictionary has the specific key.
 *
 * @param[in] array			Reference to an array object.
 * @param[in] key			The specific key.
 *
 * @return	<b>TRUE</b> means exist, while <b>FALSE</b> means not exist.<br>
 */
Boolean FGSPDFDictionaryHasKey(FGSPDFObjectRef dict, CFStringRef key); 

/** 
 * @brief Get direct reference to the object (include reference).
 *
 * @param[in] dict			Reference to a dictionary object.
 * @param[in] key			The specific key.
 *
 * @return A FGSPDFObjectRef reference that receives the specified object.
 */
FGSPDFObjectRef FGSPDFDictionaryGetElement(FGSPDFObjectRef dict, CFStringRef key);

/** 
 * @brief Get the string data for the element specified by key.
 *
 * @param[in] dict			Reference to a dictionary object.
 * @param[in] key			The specific key.
 * @param[in] bUnicode		The output unicode flag.
 *
 * @return  A Byte string or Unicode string specified by key.
 */
CFStringRef FGSPDFDictionaryCopyString(FGSPDFObjectRef dict, CFStringRef key, Boolean bUnicode); 
    
/** 
 * @brief Get the Integer data for the element specified by key.
 *
 * @param[in] dict			Reference to a dictionary object.
 * @param[in] key			The specific key.
 *
 * @return  A Integer element that matching the specific key.
 */
SInt32 FGSPDFDictionaryGetInteger(FGSPDFObjectRef dict, CFStringRef key);

/** 
 * @brief Get the Floating-point data for the element specified by key.
 *
 * @param[in] dict			Reference to a dictionary object.
 * @param[in] key			The specific key.
 *
 * @return  A Floating-point element that matching the specific key.
 */
Float32 FGSPDFDictionaryGetFloat(FGSPDFObjectRef dict, CFStringRef key);

/** 
 * @brief Get the Matrix data for the element specified by key.
 *
 * @param[in] dict			Reference to a dictionary object.
 * @param[in] key			The specific key.
 *
 * @return  A Matrix element that matching the specific key.
 */
CGAffineTransform FGSPDFDictionaryGetMatrix(FGSPDFObjectRef dict, CFStringRef key);

/** 
 * @brief Get the rect data for the element specified by key.
 *
 * @param[in] dict			Reference to a dictionary object.
 * @param[in] key			The specific key.
 *
 * @return  A Rect element that matching the specific key.
 */
CGRect FGSPDFDictionaryGetRect(FGSPDFObjectRef dict, CFStringRef key);

/** 
 * @brief Get the dictionary data for the element specified by key.
 *
 * @param[in] dict			Reference to a dictionary object.
 * @param[in] key			The specific key.
 *
 * @return  A Dictionary element that matching the specific key.
 */
FGSPDFObjectRef FGSPDFDictionaryGetDict(FGSPDFObjectRef dict, CFStringRef key);
    
/** 
 * @brief Get the array data for the element specified by key.
 *
 * @param[in] dict			Reference to a dictionary object.
 * @param[in] key			The specific key.
 *
 * @return  A Array element that matching the specific key.
 */
FGSPDFObjectRef FGSPDFDictionaryGetArray(FGSPDFObjectRef dict, CFStringRef key);

/** 
 * @brief Get the stream data for the element specified by key.
 *
 * @param[in] dict			Reference to a dictionary object.
 * @param[in] key			The specific key.
 *
 * @return  A Stream element that matching the specific key.
 */
FGSPDFObjectRef FGSPDFDictionaryGetStream(FGSPDFObjectRef dict, CFStringRef key);

/** 
 * @brief Set a FGSPDFObjectRef object specified by key.
 *
 * @param[in] dict			Reference to a dictionary object.
 * @param[in] key			The specific key.
 * @param[in] obj			The input element object.
 *
 * @return ::kFGSErrorSuccess means success.<br>
 *		   For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFDictionarySetAt(FGSPDFObjectRef dict, CFStringRef key, FGSPDFObjectRef value); 

/** 
 * @brief Remove a FGSPDFObjectRef object specified by key.
 *
 * @param[in] dict			Reference to a dictionary object.
 * @param[in] key			The specific key.
 *
 * @return ::kFGSErrorSuccess means success.<br>
 *		   For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFDictionaryRemoveAt(FGSPDFObjectRef dict, CFStringRef key);

/** 
 * @brief Set a string object specified by key.
 *
 * @param[in] dict			Reference to a dictionary object.
 * @param[in] key			The specific key.
 * @param[in] bHex			The input hex flag.
 * @param[in] string		The input string element object.
 * @param[in] bUnicode		The input unicode flag.	
 *
 * @return ::kFGSErrorSuccess means success.<br>
 *		   For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFDictionarySetAtString(FGSPDFObjectRef dict, CFStringRef key, Boolean hex, CFStringRef string, Boolean bUnicode);

/** 
 * @brief Set a Integer element specified by key.
 *
 * @param[in] dict			Reference to a dictionary object.
 * @param[in] key			The specific key.
 * @param[in] number		The Integer element object.
 *
 * @return ::kFGSErrorSuccess means success.<br>
 *		   For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFDictionarySetAtInteger(FGSPDFObjectRef dict, CFStringRef key, SInt32 number); 

/** 
 * @brief Set a Floating-point element specified by key.
 *
 * @param[in] dict			Reference to a dictionary object.
 * @param[in] key			The specific key.
 * @param[in] number		The Floating-point element object.
 *
 * @return ::kFGSErrorSuccess means success.<br>
 *		   For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFDictionarySetAtFloat(FGSPDFObjectRef dict, CFStringRef key, Float32 number);
    
/** 
 * @brief Set a name object specified by key.
 *
 * @param[in] dict			Reference to a dictionary object.
 * @param[in] key			The specific key.
 * @param[in] bHex			The input hex flag.
 * @param[in] name			The input name string object.
 * @param[in] bUnicode		The input unicode flag.	
 *
 * @return ::kFGSErrorSuccess means success.<br>
 *		   For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFDictionarySetAtName(FGSPDFObjectRef dict, CFStringRef key, CFStringRef name, Boolean bUnicode); 

/** 
 * @brief Get the dictionary of the stream object.
 *
 * @param[in] stream		Reference to a stream object.		
 *
 * @return A FGSPDFObjectRef object that receives the dictionary object.
 */
FGSPDFObjectRef FGSPDFStreamGetDict(FGSPDFObjectRef stream); 

/** 
 * @brief Get the stream data.
 *
 * @param[in] stream		Reference to a stream object.
 * @param[in] rawData		Whether access the stream data rawly.	
 * @param[out] data			A CFMutableDataRef object that receives stream data.
 *
 * @return ::kFGSErrorSuccess means success.<br>
 *		   For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFStreamCopyData(FGSPDFObjectRef stream, Boolean rawData, CFMutableDataRef data);

/** 
 * @brief Set the stream data.
 *
 * @param[in] stream		Reference to a stream object.
 * @param[in] data			A CFDataRef object that contains stream data.
 *
 * @return ::kFGSErrorSuccess means success.<br>
 *		   For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFStreamSetData(FGSPDFObjectRef stream, CFDataRef data);
    
#ifdef __cplusplus
};
#endif

#endif // __FGSPDFOBJECT__
/**@}*/
